Java bindings for LP/MIP/QP - #1524

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

_{Comment @coderabbitai help to get the list of available commands.}

Sorry that was an accident. Reopening.

@chris-maes thanks for the review — replying to the C API comments in one place since they're connected.

Two facts first, because I think one of them changes the picture

There is no solution-scoped attribute API today. All five attribute getters are cuOptGetProblem*Attribute, and every CUOPT_ATTR_* / CUOPT_ARRAY_ATTR_* constant is problem-scoped. So these stats aren't reachable through attributes at present — your "and if not, they should be" is the actual proposal, and it means adding cuOptGetSolutionIntAttribute / cuOptGetSolutionFloatAttribute plus a CUOPT_SOLUTION_ATTR_* block.

None of these stats were reachable by any route before this PR. Checking main, of the eleven fields in #1202 — primal/dual residual, gap, iteration count, solved-by, presolve time, node count, simplex iterations, and the three violation metrics — zero are exposed. The solution accessors that do exist (cuOptGetTerminationStatus, cuOptGetObjectiveValue, cuOptGetMIPGap, cuOptGetSolutionBound, cuOptGetSolveTime, primal/dual/reduced costs) cover the outcome, not the diagnostics. Note cuOptGetMIPGap is the MIP optimality gap, which is a different quantity from the LP primal-dual gap in that list.

Why we think they're worth supporting

The data already exists on lp_solution_interface_t / mip_solution_interface_t, so this is pure exposure — no computation, no solve-time cost. Concretely:

• Judging a non-optimal answer. When a solve returns on a time limit rather than OPTIMAL, residuals and gap are the only way to tell a nearly-converged solution from a useless one. Without them a C-ABI caller sees a status and a vector of numbers and cannot assess them.
• Verifying a returned MIP solution. max_constraint_violation, max_int_violation, and max_variable_bound_violation are what a caller checks before acting on a solution in production. This is the one we'd argue hardest for.
• Knowing which algorithm actually solved it. With CUOPT_METHOD_CONCURRENT the caller otherwise cannot tell whether PDLP or dual simplex produced the answer, which matters for tuning and reproducibility.
• Performance work. Iteration counts, node counts, simplex iterations, and presolve time are the basis for benchmarking and spotting regressions.

Two more general points. Python already exposes all of this by binding to the C++ structs through Cython, so today the C ABI is a second-class path — that asymmetry is what #1202 was filed about. And users arriving from Gurobi or CPLEX expect IterCount / NodeCount / violation metrics as a matter of course.

Where we agree, and what we'd propose

Attributes are the right shape for these. All eleven are scalar ints and floats, which is exactly what the attribute model is for. There's also a maintenance argument specific to the bindings: cuOpt already generates CuOptConstants.java from constants.h, so a new attribute constant reaches Java with zero hand-written code, whereas a new function needs a JNI entry point, a native declaration, and a wrapper. Every future stat would be free on the binding side. That argues for attributes over the eleven individual getters proposed in #1202 as well.

What we'd suggest is a shape-based rule rather than attributes everywhere, since it's the rule the C API already follows:

• scalars (stats, flags, counts) → attributes
• homogeneous arrays sized by a known dimension (bounds, senses) → array attributes
• structured, ragged, or multi-output → dedicated functions

The third case is why cuOptGetConstraintMatrix is a function rather than an attribute: CSR is three parallel arrays. The same applies to the quadratic constraint rows in #1703, where each row is a variable-length record containing variable-length arrays — no attribute scheme expresses that.

Happy to convert the two bulk cuOptGet{LP,MIP}SolverStats calls in this PR to solution attributes on that basis. It's more work than what's here now, but nothing has shipped yet, so it costs no deprecation or ABI break — this is the cheapest moment to change direction.

Conceded

cuOptSolutionIsMIP should go. You're right. It's redundant: Solution is already constructed with the problem's category, so the Java side has the answer without a native call, and a C caller normally holds the problem handle for cuOptIsMIP. We'll drop it.

The hyperparameters_only flag should go too — agreed that a public header shouldn't advertise the concept. We'll remove the flag and always dump non-hyperparameters.

One question back

On the parameter calls (cuOptLoadParametersFromFile, cuOptDumpParametersToFile, cuOptGetNumSolverParameters, cuOptGetSolverParameterName): the use case is settings introspection and file round-tripping, matching what Python offers — Java's getSolverSettingNames() and load/dumpSettingsToFile are built on them. They're convenience rather than necessity, and we're happy to drop them from this PR if you'd rather keep the C API lean and revisit separately.

/ok to test 5972293

IMO changes to the C API should be in a separate PR, not combined with a 7000 line diff here.

/ok to test 4eb70d8

@mlubin agreed — the C API changes are now #1715, off main, 318 lines across 4 files with no reference to Java.

This PR is stacked on it. The cpp/ changes still show in this diff because the Java bindings call cuOptGetSolutionIntAttribute / cuOptGetSolutionFloatAttribute and would not build without them; they will drop out of this diff automatically once #1715 merges and main is merged back in.

Two related issues were also split out of the earlier discussion, so each is reviewable on its own:

• [BUG] Copy-out solution accessors cannot distinguish "no data" from "data is all zeros" #1706 — copy-out solution accessors cannot distinguish "no data" from "data is all zeros". Filed as a bug, per your point that it is a C API behaviour issue rather than a reason for a Java-specific interface.
• [FEA] Expand cuopt_c.h with problem-model accessors for non-Python language bindings #1703 — the remaining C API problem-model gaps, trimmed to cover only missing accessors.

#1705 is closed: you were right that runtime parameter enumeration is unnecessary. Every one of the 117 parameter registrations is written as a CUOPT_* macro from constants.h, and none of the 109 distinct registered names is missing from the header, so a binding generated from that header has the complete set by construction.

/ok to test d981aec

/ok to test 6a04604

/ok to test 8d854d3

/ok to test dc8b4b0

@chris-maes before I work through the rest of your review, I'd like to check the direction, because I think the remaining comments share one underlying question and answering it settles most of them at once.

What's already done

• IP is gone from ProblemCategory and from the docs. The native value still has to be mapped, since the engine returns a third category when every variable is discrete (cpu_optimization_problem.cpp), so it is folded into MIP with a comment saying why.
• readMPS / writeMPS are gone; read dispatches on the file extension and write replaces writeMPS. This also deleted the parseMPSProblem JNI entry point, which was the only remaining caller of io::read_mps.
• getCSR / getQCSR are now getConstraintMatrix / getQuadraticObjectiveMatrix. You were right to ask what a "linear objective matrix" was — the documentation was wrong, getCSR returned the constraint matrix.
• The five C API comments are addressed and merged separately as Expose solver statistics as scalar solution attributes #1715.

On "fluent": @mlubin noted it is standard terminology for this style of API, so I have left the wording unless you would still prefer it changed.

The question

The Java surface was built for parity with the Python API — that was its design goal, and it is why the shape looks the way it does. Your review is asking it to be consistent with the C API instead, which took the attribute direction in #1549.

Both are reasonable, but they point different ways, and five of the six items you have asked to remove exist in the Python API today:

So the choice is roughly:

(a) Java aligns with the C API and diverges from Python. Java becomes the model the Python API moves toward later. Users moving between the two see different shapes until Python follows.

(b) Java matches Python for now, and both move to an attribute model together as a separate piece of work.

isSolved is the exception either way — it is not in Python and getStatus covers it, so I will remove it regardless.

What each remaining item would mean

ObjectiveExpression — it is the interface returned by getObjective, implemented only by LinearExpression and QuadraticExpression. Removing it means getObjective returns one of those two, so callers either get overloads or an instanceof check. Cheap either way; mostly a question of what you want the return type to be.

ProblemCategory — one wrinkle worth flagging. You asked why cuOptSolutionIsMIP existed when cuOptIsMIP was available. I removed it, and Solution now derives isMIP() from the problem's ProblemCategory rather than calling native. If ProblemCategory also goes, Solution needs CUOPT_ATTR_IS_MIP as its source instead. Fine either way, but the two changes interact.

getPrimalSolution / getDualSolution / getReducedCost — these already exist per-variable and per-constraint (Variable.getValue(), Variable.getReducedCost(), Constraint.getDualValue()), populated after each solve. The array forms are an additional bulk path. Removing them is straightforward; the thing lost is copying a whole solution vector out in one call, which matters for large models. Happy to remove if you would rather have one way to do it.

computeSlack in the C++ engine — agreed on the principle: if each binding computes slack itself, they can disagree on tolerances or on how quadratic constraints are handled. That is a C++ change though, so by the precedent from #1715 it should be its own PR. Can that follow separately rather than block this one?

"Attributes instead of stats" — this is the one I would most like pinned down, since it subsumes several of the above. Do you mean:

1. a thin Java wrapper over the CUOPT_SOLUTION_ATTR_* accessors that just merged, keeping LPStats / MIPStats as the presentation; or
2. a genuinely attribute-shaped Java API, where a caller fetches values by selector rather than through typed accessors?

Option 2 is a much larger change and would be unusual for Java, where typed accessors are the norm and an untyped selector API gives up compile-time checking. Option 1 I can do now.

Last thing

This PR is around 6,700 lines and has been open since July. Which of these do you consider blocking for merge, and which could land as follow-ups against the Java module once it is in? If most can follow, the bindings become reviewable on their own merits and the API refinement can proceed without holding up CI coverage and the build integration.

/ok to test 8b178d9